home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1995 October / EnigmA AMIGA RUN 01 (1995)(G.R. Edizioni)(IT)[!][issue 1995-10][Aminet 7].iso / Aminet / comm / fido / FQUERY.lha / ftsc / find.txt
Text File  |  1995-02-16  |  13KB  |  282 lines
  1.  Document:   fsc-00xx
  2.  Version:    0.5
  3.  Date        Feb 16,1995
  4.  Title:      Implementation and Usage of FileFind Utilities
  5.  Authors:    Robert Williamson FidoNet#1:167/104.0  robert@ecs.mtlnet.org
  6.  
  7.   Intro
  8.  
  9.     A portion of the document is derived from information in
  10.       AllFix.DOC by Harald Harms @ 2:281/910 
  11.     with  additional  sections  from 
  12.       FQuery.DOC by Robert Williamson @ 1:167/104 
  13.  
  14.     The  MSdos  program ALLFIX by Harald Harms first introduced the idea of
  15.     searching for files via echomail.  The term applied to this function is
  16.     'FileFind'.   A  FileFind system allows sysops, points and BBS users to
  17.     search for files by placing a message to 'ALLFIX' in an echo designated
  18.     for  the  purpose  of  finding files.  All FTN sites running a FileFind
  19.     processor which is configured to scan that echo will reply to that user
  20.     if  there  any files matching his query.  This system provides a method
  21.     for  searching  many  FTN  sites  throughout  the  world, with a single
  22.     message.
  23.  
  24.     FileFind  programs  work  by scanning through defined message bases for
  25.     messages  to  the  default  name  ALLFIX.   All  FileFind programs MUST
  26.     respond  to  the name ALLFIX, but may also respond to the name FileFind
  27.     and  the  name of the particular FileFind program in use.  The FileFind
  28.     program  will  process  these messages, examining the Subject field for
  29.     search queries.  If any valid query is found, the FileFind program will
  30.     search  the  sites files database for files matching the users's query.
  31.     If  the  FileFind  program  finds any matches, it will generate a reply
  32.     containing  a list of the files found, and some basic information ABOUT
  33.     the  system  posting  the reply.  When the user who initially wrote the
  34.     request  reads  the reply, he will then be able to decide if any of the
  35.     reported  files  meet  his  needs,  and  from the ABOUT included in the
  36.     reply, learn where and how he may get those files.
  37.  
  38.  
  39.   FileFind Query Message Structure
  40.  
  41.     To: name_of_FileFind program
  42.     The  message  must be addressed to ALLFIX so that all FileFind programs
  43.     can  respond.   To  use  features  specific  to  a  particular FileFind
  44.     program,  or  to  limit  the  responses  to  a particular platform, the
  45.     message  should  be  addressed  to  that program's name.  Some FileFind
  46.     programs  will  respond  to more than two names.  
  47.  
  48.     Subject:  
  49.     A  space-separated  list  of  file  specifications,  keywords or quoted
  50.     strings.
  51.  
  52.     keyword     - single word preceeded by a '/' with no intervening spaces,
  53.                   must be at least 3 characters, not including the '/'.
  54.                   a keyword search is in actually a substring search of the
  55.                   site's filelist.  
  56.  
  57.     description - string enclosed in double-quotes,
  58.                   if a single word, must be more than 3 characters.
  59.  
  60.     filespec    - single word, no spaces, no double-quotes or preceding /,
  61.                   must be at least 3 characters, not including any wildcard
  62.                   or pattern matching charcaters, such as '*'.
  63.                   Messages addressed to ALLFIX must not have any embedded
  64.                   pattern matching characters.
  65.  
  66.  
  67.     The  minimum number of characters for description, keyword and filespec
  68.     queries  is  an  implementation  detail of the FileFind program.  These
  69.     values  should  be configurable, but should never be settable to values
  70.     of less than 3.
  71.  
  72.     Each  implementation should allow the operator the ability to configure
  73.     a list of disallowed keywords.
  74.  
  75.   NetMail Queries
  76.  
  77.     Some FileFind programs may also have the ability to process file search
  78.     queries received as netmail and addressed to the name of the particular
  79.     program.   In  this  case,  all  replies are via netmail also.  
  80.  
  81.   NetMail Commands
  82.     FileFind   Netmail   commands   are   identifed   by   a  leading  '%'.
  83.     Implementation  of  netmail  commands  is  optional.   If  implemented,
  84.     Compliant  FileFind  utilities  should be able to process the following
  85.     minimum NetMail command set.
  86.     
  87.     %help       - netmail only, returns an extended help text for the 
  88.                   FileFind program, the ABOUT of the the site and a list
  89.                   of MAGIC freqable names.
  90.     %about      - netmail only, returns the ABOUT of the site and a full
  91.  or %magic        list of MAGIC names.
  92.  
  93.     %newfiles   - netmail only, returns the NEWFILES list of the site
  94.  or %new          via netmail.
  95.  
  96.  
  97.  
  98.   The Site ABOUT
  99.  
  100.     Obviously, a system that neither accepts file requests nor allows users
  101.     to  download  on  their first call should not be responding to FileFind
  102.     messages.   If  there are any limitations for the caller to acquire any
  103.     of  the  files  that the site has advertised as being available in it's
  104.     FileFind response, these limitations MUST be listed in the reply.  This
  105.     information  should  be  included  in  the ABOUT file that the FileFind
  106.     program user creates.
  107.  
  108.     The  site ABOUT should contain the following information.  The FileFind
  109.     program implementor should instruct his users on these requirements.
  110.  
  111.       - sitename
  112.       - site operator's name
  113.       - complete phonenumber
  114.       - baud rate
  115.       - hours during which filerequests are accepted, if at all
  116.       - hours during which users can download
  117.       - conditions for file requests and user downloads
  118.       NOTE: the above information should be within the first 14 lines.
  119.       optional:
  120.       - a list a MAGIC names      
  121.       - an indication if magic names are also available to terminal users.
  122.  
  123.   Searching for Files and Creating Replies
  124.  
  125.     The method used by the FileFind program to search for requests is up to
  126.     the  implementor.   However,  if searching a list, the FileFind program
  127.     should  confirm  the actual existance of all files that match the query
  128.     specification.
  129.  
  130.     The FileFind program should only process description strings, filespecs
  131.     or  keywords  that contain more than 3 valid characters and should have
  132.     configuration  options  to define greater minimum lengths on a per-echo
  133.     basis.
  134.  
  135.     For  filespecs,  the  wildcard  character  '*'  IS  considered  a valid
  136.     specification  as  well  as the '?' wildcard, but only the '?' is to be
  137.     counted  as  a  character  when  determining the length of query.  File
  138.     extensions  are  not necessary and any characters AFTER a '*' are to be
  139.     ignored.   The  FileFind  program should be configurable so as to allow
  140.     replacement  all  of the file extensions with '.*' or '#?' dependant on
  141.     platform.   This  results  in  queries being independant of the various
  142.     archivers in use.
  143.  
  144.     Replies
  145.  
  146.     Replies  created by FileFind utilities are expected to be in compliance
  147.     with the following FTN specifications:
  148.         FTS-0001    -  packed message format
  149.         FTS-0009    -  MSGID/REPLY
  150.         FSC-0046    -  PID and tear line
  151.  
  152.     In  addition, a FileFind utility may use the FID:  control line for any
  153.     information needed that cannot be put in a PID:  without violating that
  154.     specification.
  155.  
  156.         ^AFID: ascii text CR
  157.  
  158.     Must be less than 80 characters including ^A and terminating CR.
  159.  
  160.     There  are three ways in which the FileFind program can create replies:
  161.         - write the replies in the echo in which the query appeared.
  162.         - write the replies in an echo that has been specifically
  163.           designated for that purpose in the particular FTN or for
  164.           a gorup of echos in that FTN.  
  165.         - reply via routed netmail.
  166.  
  167.     Since  each FTN site connected to a particular FileFind program area is
  168.     capable  of  creating an information reply, there is much concern as to
  169.     the   amount  of  traffic  that  can  be  generated,  FileFind  program
  170.     developers  must  be sensitive to these concerns by providing the means
  171.     to  their users to limit the traffic on a per-echo basis.  For example,
  172.     various  FileFind  echos  have  rules  limiting  the  size or number of
  173.     replies,  or  the length of the system information that may be included
  174.     in a reply.
  175.  
  176.   Limiting replies
  177.  
  178.     It is strongly suggested that some default limitations be built-in.
  179.  
  180.     Limiting Site Header (ABOUT):
  181.  
  182.     If the site's ABOUT, (the text that has been configured in order to add
  183.     the system's information and Magic names list to the reply), is greater
  184.     than  14  lines,  the remainder should NOT be posted.  A line should be
  185.     added  to  the  response indicated this, and the user may be invited to
  186.     either  Freq  or  download  the MAGIC name's ABOUT or MAGIC, for a full
  187.     list of magic names.  The FileFind program may optionally send the full
  188.     system information and magic name list via routed netmail.
  189.  
  190.     Limiting Match List due to ambiguity of query:
  191.  
  192.     If  the  list of matches (note:  not the size of the message itself) is
  193.     greater  than  32K,  the  FileFind program should post a message to the
  194.     user to indicate that his query may have been too ambiguous and perhaps
  195.     invite him to freq or download the MAGIC name FILES for a full list.
  196.  
  197.     Splitting Match List into Multiple Messages:
  198.  
  199.     If  the  list  of  matches is greater than 10K, it should be split into
  200.     multiple  messages  of  no more than 8K.  Although the backbone permits
  201.     messages  up  to  16K  in length, 8K is a more readable size.  Only the
  202.     first  split  message  may  contain  the ABOUT information of the site.
  203.     Each  message must be given both a unique Subject field (eg:  prepended
  204.     by  "Part n/n") and a unique MSGID:.  This because some tossers may use
  205.     either or both for dupe detection.
  206.  
  207.     Limiting Number of Split Messages:
  208.  
  209.     If the number of messages is greater than the preset limit of the echo,
  210.     and the FileFind Program does not have an option to forward the replies
  211.     via netmail, the replies should be discarded and the user informed that
  212.     his request may have been too amibiguous.
  213.  
  214.  
  215.     NetMail Reply:
  216.  
  217.     The  FileFind  program  may  have  an option to forward all replies via
  218.     routed netmail, or to do so under certain conditions as outlined above.
  219.     Obviously, if the FileFind program can process netmail queries, it MUST
  220.     respond via netmail.
  221.  
  222.     User NetMail Reply Request:
  223.  
  224.     Alternativly  the  user  can  request  a netmail reply for his echomail
  225.     query by preceeding the query with either "%" or "!".
  226.       eg;
  227.         Subject:  % /fsc /fts
  228.  
  229.     If  the  FileFind  program  does  not  support  this  feature,  it must
  230.     ignore  any  echomail  query message that has a "%" or "!" as the first
  231.     WORD of the Subject field.
  232.  
  233.     Second Reply or Extended Response Request:
  234.  
  235.     The  FileFind  site  indicates availablility of Second Reply by placing
  236.     the string 'program_name 4d_address' in the From:  field
  237.     of the message.
  238.         eg: FROM: FQUERY 1:167/104.0 
  239.  
  240.     When  a  user  replies  to a FileFind reply, the message will be to the
  241.     FileFind  program  @  {network  address}.  When processing the FileFind
  242.     conferences, the FileFind program will treat any message to itself that
  243.     includes the site address as a Second Reply Request.
  244.  
  245.     If this feature is available, the FileFind program will include up to a
  246.     maximum  of  15 files (maximum 12K match list) in it's replies.  If the
  247.     user  wants  a more detailed listing, he simply replies to the FileFind
  248.     program's  reply.   Only  the system thatposted the original reply will
  249.     respond to that new request.  This second, specific reply, will contain
  250.     up  to  50  files  (32K  of matchlist) either including or SKIPPING the
  251.     first  15.   These  numbers  may  be  replaced  by  byte limits in some
  252.     implementations.
  253.  
  254.  
  255.     No Second Reply in Designated Reply Echo:
  256.  
  257.     The  Designated  Reply  Echo  method does not allow replies to be made,
  258.     because  the FileFind program may not be permitted to scan a Designated
  259.     Reply  Echo.  The FileFind program should automatically report up to 50
  260.     files  for any requests.  Therefore, the traffic limitaion features may
  261.     be  disabled for networks that require the FileFind program to reply in
  262.     a Designated Reply Echo, and disallow Second Reply in that echo.
  263.  
  264.     Disable Local Messages:
  265.  
  266.     The FileFind program must be able to to disable the processing of local
  267.     messages.   What  this  means  is  that  the  FileFind program will not
  268.     process  any messages generated on that FTN site, including messages by
  269.     the  sysop  using  an  offline  reader,  or by a site's BBS or off-line
  270.     reader users.  This should NOT exclude messages from a site's points.
  271.  
  272.  
  273.     Limit by Age:
  274.  
  275.     The  FileFind  program  must  be  configurable so that the operator can
  276.     limit  the  age  of an query message that is acceptable for processing.
  277.     This  should  be  in  number  of  days.   The  FileFind  program may be
  278.     configured  to  process all the FileFind requests regardless of how old
  279.     they are.  Age should never be greater than 365 days.
  280.  
  281.  -eot-
  282.